-
-
- <para> The duplicate filter is designed to remove duplicate
- points based on their shortname (traditionally a waypoint's
- name on the GPS receiver), and/or their location (to a
- precision of 6 decimals). This filter supports two options
- that specify how duplicates will be recognized, "<parameter moreinfo="none">shortname</parameter>" and "<parameter moreinfo="none">location</parameter>". Generally, at least
- one of these options is REQUIRED. </para>
- <example id="duplicate_to_suppress_points">
- <title>Using duplicate filter to suppress points with same name and locations</title>
- <screen format="linespecific"> gpsbabel -i gpx -f 1.gpx -f 2.gpx -x duplicate,location,shortname \
- -o gpx -F merged_with_no_dupes.gpx</screen>
- </example>
- <para> would remove points that have duplicate shortnames
- *AND* duplicate locations. The result would be a GPX file
- that more than likely contains only unique points and point
- data.</para>
- <para> The duplicate filter can also take an "all" option.
- If you specify that option, all instances of a duplicated
- waypoint will be removed, not just the second and subsequent
- instances. If your input file contains waypoints A, B, B,
- and C, the output file will contain waypoints A, B, and C
- without the "all" option, or just A and C with the "all"
- option. This option can be useful as an "ignore list" in
- some circumstances.
+<para>
+The duplicate filter is designed to remove duplicate points based on their
+short name (traditionally a waypoint's name on the GPS receiver), and/or
+their location (to a precision of 6 decimals). This filter supports two
+options that specify how duplicates will be recognized,
+<option>shortname</option> and <option>location</option>.
+Generally, at least one of these options is required.
</para>
- <para> Finally, the duplicate filter takes a
- "<option>correct</option>" option. If you specify that
- option, the latitude and longitude frmo later duplicates will
- replace the latitude and longitude in earlier waypoints. You
- can use this to apply a list of "<emphasis role="bold">waypoint corrections</emphasis>" to a larger
- file, while keeping all of the other details from the larger
- file.</para>
+<example id="duplicate_to_suppress_points">
+ <title>Using the duplicate filter to suppress points with the same
+ name and location</title>
+ <para>
+ This command line removes points that have duplicate short names
+ and duplicate locations. The result would be a
+ <link linkend="fmt_gpx">gpx</link> file that more than likely
+ contains only unique points and point data.
+ </para>
+ <screen format="linespecific"> gpsbabel -i gpx -f 1.gpx -f 2.gpx -x duplicate,location,shortname -o gpx -F merged_with_no_dupes.gpx</screen>
+</example>
+<para>
+When this option is specified, GPSBabel will remove all instances of a
+duplicated waypoint, not just the second and subsequent instances. If
+your input file contains waypoints A, B, B, and C, the output file will
+contain waypoints A, B, and C without the <option>all</option> option,
+or just A and C with the <option>all</option> option.
+</para>
+<example id="duplicate_to_ignore">
+<title>Using the duplicate filter to implement an "ignore list."</title>
+<para>
+This option may be used to implement an "ignore list." In the following
+example, the duplicate filter is used to remove a list of waypoints to be
+ignored from a larger collection of waypoints:
+</para>
+<screen format="linespecific">gpsbabel -i gpx -f waypoints.gpx -i csv -f to_ignore.csv -x duplicate,shortname,all -o gpx -f filtered.gpx</screen>
+</example>
-
+<para>
+This option is used to change the locations of waypoints without losing any
+of the other associated information. When this option is specified, the
+latitude and longitude from later duplicates will replace the latitude and
+longitude in the original waypoint.
+</para>
+<para>
+As an example, this option may be used to adjust the locations of "puzzle"
+geocaches in a Groundspeak pocket query:
+</para>
+<example id="Correcting_Cache_Locations">
+<title>Using the duplicate filter to correct the locations of "puzzle"
+geocaches</title>
+<screen format="linespecific">gpsbabel -i gpx -f 43622.gpx -i csv -f corrections.csv -x duplicate,shortname,correct -o gpx -F 43622-corrected.gpx</screen>
+<para>
+After this command is run, the waypoints in the output file will have all
+of the descriptive information from <filename>43622.gpx</filename>, but
+waypoints that were also found in <filename>corrections.csv</filename>
+will have their coordinates replaced with the coordinates from that file.
+</para>
+</example>
+<para>
+This option causes the duplicate filter to remove any additional waypoint
+that has the same coordinates (to six decimal degrees) as a waypoint that
+came before. This option may be used to remove duplicate waypoints if the
+names are not expected to be the same. It also might be used along with the
+<option>shortname</option> option to remove duplicate waypoints if the names
+of several unrelated groups of waypoints might be the same.
+</para>
+<para>
+This option is the one most often used with the duplicate filter. This
+option instructs the duplicate filter to remove any waypoints that share
+a short name with a waypoint that has come before. This option might be
+used to remove duplicates if you are merging two datasets that were
+each created in part from a common ancestor dataset.
+</para>
+
+<para>
+This option specifies the name of a route. If this option is specified, the
+radius filter puts all points that are kept into a route with the given name.
+The order of points in the route is by distance from the center (unless the
+<option>nosort</option> option is also specified.)
+</para>
+<para>
+Note that this route is not necessarily the most efficient route to visit
+all of the points. In fact, for some data sets, it might be the least
+efficient route.
+</para>
+
-
+<para>
+This option is required.
+</para>
+<para>
+This option specifies the maximum distance a point may be from the central
+point in order to remain in the dataset. Points closer than this distance
+will be kept and points further away will be removed (unless the
+<option>exclude</option> option is specified.)
+</para>
+<para>
+Distances may be expressed in miles (3M) or kilometers (4K). If no units
+are provided, the distance is assumed to be in miles.
+</para>
-
+<para>
+If this option is included, the action of the radius filter will be reversed:
+points within the given distance will be removed, and points further away
+will be kept.
+</para>
-
+<para>
+This option is required.
+</para>
+<para>
+This option specifies the latitude of the central point in decimal degrees.
+South latitudes should be expressed as a negative number. Valid values for
+this option are from -90 to 90.
+</para>
-
+<para>
+This option is required.
+</para>
+<para>
+This option specifies the longitude of the central point in decimal degrees.
+West longitudes should be expressed as a negative number. Valid values for
+this option are from -180 to 180.
+</para>
-
+<para>
+This option specifies the maximum number of points that the radius filter may
+keep. If there are more than this number of points within the specified
+distance of the center, the more distant points will be discarded even though
+they are within the specified distance. If this option is not specified,
+all points are kept regardless of how many there are.
+</para>
+<para>
+Note that if the <option>nosort</option> option is also specified, this
+option will instead keep points based on their position within the input
+file rather than on their distance from the center. This may or may not be
+what you want.
+</para>
+<para>
+Note, too, that this option may be used with the <option>exclude</option>
+option, but the results might not be what you expect. In particular, the
+results will not be the same as if you had kept all of the points you'd
+otherwise throw away. You will still get no more than
+<varname>maxcount</varname> points, but they will all be at least
+<varname>distance</varname> away from the center. (And possibly sorted.)
+</para>
+
+<para>
+If this option is specified, the radius filter will not sort the remaining
+points by distance from the center. They will remain in whatever order they
+were originally.
+</para>
-
-
- <para> The radius filter is designed to include points based
- on their proximity to a central point. Distances and the
- central point are declared on the command line by passing the
- <option>distance=X.XX</option>,
- <option>lat=X.XX</option>, and
- <option>lon=X.XX</option> options to
- the filter. Distance options may be expressed in miles
- (<option>distance=3M</option>) or
- kilometers (<option>distance=3K</option>). The default is
- zero miles. Additionally, the exclude option may be
- specified to reverse the effect of the filter, so that points
- further from the center are kept and closer points are
- discarded.</para>
- <example id="radius_to_find_points_close">
- <title>Using radius filter to identify points close to a given point </title>
- <screen format="linespecific">gpsbabel -i geo -f 1.loc \
- -x radius,distance=1.5M,lat=30.0,lon=-90.0 \
- -o mapsend \
- -F 2.wpt</screen>
- </example>
- <para> would include only points within 1.5 miles of N30.000
- W90.000
+<para>
+This filter includes or excludes waypoints based on their proximity to a
+central point. All waypoints more than the specified distance from the
+specified point will be removed from the dataset.
+</para>
+<para>
+By default, all remaining points are sorted so that points closer to the
+center appear earlier in the output file.
</para>
+<example id="radius_to_find_points_close">
+ <title>Using the radius filter to find points close to a given point</title>
+ <para>This example command line would include only points within 1 1/2 miles
+ of N30.000 W 90.000</para>
+
+<screen format="linespecific">gpsbabel -i geo -f 1.loc -x radius,distance=1.5M,lat=30.0,lon=-90.0 -o mapsend -F 2.wpt</screen>
+</example>
projects / gpsbabel.git / commitdiff